home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Languguage OS 2
/
Languguage OS II Version 10-94 (Knowledge Media)(1994).ISO
/
gnu
/
elispman.lha
/
elispman
/
elisp-12
(
.txt
)
< prev
next >
Wrap
GNU Info File
|
1993-06-01
|
51KB
|
978 lines
This is Info file elisp, produced by Makeinfo-1.55 from the input file
elisp.texi.
This is edition 2.0 of the GNU Emacs Lisp Reference Manual, for
Emacs Version 19.
Published by the Free Software Foundation, 675 Massachusetts Avenue,
Cambridge, MA 02139 USA
Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.
Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.
Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Foundation.
File: elisp, Node: Output Streams, Next: Output Functions, Prev: Input Functions, Up: Streams
Output Streams
==============
An output stream specifies what to do with the characters produced
by printing. Most print functions accept an output stream as an
optional argument. Here are the possible types of output stream:
BUFFER
The output characters are inserted into BUFFER at point. Point
advances as characters are inserted.
MARKER
The output characters are inserted into the buffer that MARKER is
in at the marker position. The position advances as characters are
inserted. The value of point in the buffer has no effect when the
stream is a marker.
FUNCTION
The output characters are passed to FUNCTION, which is responsible
for storing them away. It is called with a single character as
argument, as many times as there are characters to be output, and
is free to do anything at all with the characters it receives.
The output characters are displayed in the echo area.
`nil'
`nil' specified as an output stream means that the value of
`standard-output' should be used as the output stream; that value
is the "default output stream", and must be a non-`nil' output
stream.
SYMBOL
A symbol as output stream is equivalent to the symbol's function
definition (if any).
Here is an example of a buffer used as an output stream. Point is
initially located as shown immediately before the `h' in `the'. At the
end, point is located directly before that same `h'.
---------- Buffer: foo ----------
This is t-!-he contents of foo.
---------- Buffer: foo ----------
(print "This is the output" (get-buffer "foo"))
=> "This is the output"
---------- Buffer: foo ----------
This is t
"This is the output"
-!-he contents of foo.
---------- Buffer: foo ----------
Now we show a use of a marker as an output stream. Initially, the
marker points in buffer `foo', between the `t' and the `h' in the word
`the'. At the end, the marker has been advanced over the inserted text
so that it still points before the same `h'. Note that the location of
point, shown in the usual fashion, has no effect.
---------- Buffer: foo ----------
"This is the -!-output"
---------- Buffer: foo ----------
m
=> #<marker at 11 in foo>
(print "More output for foo." m)
=> "More output for foo."
---------- Buffer: foo ----------
"This is t
"More output for foo."
he -!-output"
---------- Buffer: foo ----------
m
=> #<marker at 35 in foo>
The following example shows output to the echo area:
(print "Echo Area output" t)
=> "Echo Area output"
---------- Echo Area ----------
"Echo Area output"
---------- Echo Area ----------
Finally, we show an output stream which is a function. The function
`eat-output' takes each character that it is given and conses it onto
the front of the list `last-output' (*note Building Lists::.). At the
end, the list contains all the characters output, but in reverse order.
(setq last-output nil)
=> nil
(defun eat-output (c)
(setq last-output (cons c last-output)))
=> eat-output
(print "This is the output" 'eat-output)
=> "This is the output"
last-output
=> (10 34 116 117 112 116 117 111 32 101 104
116 32 115 105 32 115 105 104 84 34 10)
Now we can put the output in the proper order by reversing the list:
(concat (nreverse last-output))
=> "
\"This is the output\"
"
File: elisp, Node: Output Functions, Next: Output Variables, Prev: Output Streams, Up: Streams
Output Functions
================
This section describes the Lisp functions for printing Lisp objects.
Some of the Emacs printing functions add quoting characters to the
output when necessary so that it can be read properly. The quoting
characters used are `\' and `"'; they are used to distinguish strings
from symbols, and to prevent punctuation characters in strings and
symbols from being taken as delimiters. *Note Printed
Representation::, for full details. You specify quoting or no quoting
by the choice of printing function.
If the text is to be read back into Lisp, then it is best to print
with quoting characters to avoid ambiguity. Likewise, if the purpose is
to describe a Lisp object clearly for a Lisp programmer. However, if
the purpose of the output is to look nice for humans, then it is better
to print without quoting.
Printing a self-referent Lisp object requires an infinite amount of
text. In certain cases, trying to produce this text leads to a stack
overflow. Emacs detects such recursion and prints `#LEVEL' instead of
recursively printing an object already being printed. For example,
here `#0' indicates a recursive reference to the object at level 0 of
the current print operation:
(setq foo (list nil))
=> (nil)
(setcar foo foo)
=> (#0)
In the functions below, STREAM stands for an output stream. (See
the previous section for a description of output streams.) If STREAM
is `nil' or omitted, it defaults to the value of `standard-output'.
- Function: print OBJECT &optional STREAM
The `print' is a convenient way of printing. It outputs the
printed representation of OBJECT to STREAM, printing in addition
one newline before OBJECT and another after it. Quoting
characters are used. `print' returns OBJECT. For example:
(progn (print 'The\ cat\ in)
(print "the hat")
(print " came back"))
-|
-| The\ cat\ in
-|
-| "the hat"
-|
-| " came back"
-|
=> " came back"
- Function: prin1 OBJECT &optional STREAM
This function outputs the printed representation of OBJECT to
STREAM. It does not print any spaces or newlines to separate
output as `print' does, but it does use quoting characters just
like `print'. It returns OBJECT.
(progn (prin1 'The\ cat\ in)
(prin1 "the hat")
(prin1 " came back"))
-| The\ cat\ in"the hat"" came back"
=> " came back"
- Function: princ OBJECT &optional STREAM
This function outputs the printed representation of OBJECT to
STREAM. It returns OBJECT.
This function is intended to produce output that is readable by
people, not by `read', so quoting characters are not used and
double-quotes are not printed around the contents of strings. It
does not add any spacing between calls.
(progn
(princ 'The\ cat)
(princ " in the \"hat\""))
-| The cat in the "hat"
=> " in the \"hat\""
- Function: terpri &optional STREAM
This function outputs a newline to STREAM. The name stands for
"terminate print".
- Function: write-char CHARACTER &optional STREAM
This function outputs CHARACTER to STREAM. It returns CHARACTER.
- Function: prin1-to-string OBJECT &optional NOESCAPE
This function returns a string containing the text that `prin1'
would have printed for the same argument.
(prin1-to-string 'foo)
=> "foo"
(prin1-to-string (mark-marker))
=> "#<marker at 2773 in strings.texi>"
If NOESCAPE is non-`nil', that inhibits use of quoting characters
in the output. (This argument is supported in Emacs versions 19
and later.)
(prin1-to-string "foo")
=> "\"foo\""
(prin1-to-string "foo" t)
=> "foo"
See `format', in *Note String Conversion::, for other ways to
obtain the printed representation of a Lisp object as a string.
File: elisp, Node: Output Variables, Prev: Output Functions, Up: Streams
Variables Affecting Output
==========================
- Variable: standard-output
The value of this variable is the default output stream, used when
the STREAM argument is omitted or `nil'.
- Variable: print-escape-newlines
If this variable is non-`nil', then newline characters in strings
are printed as `\n'. Normally they are printed as actual newlines.
This variable affects the print functions `prin1' and `print', as
well as everything that uses them. It does not affect `princ'.
Here is an example using `prin1':
(prin1 "a\nb")
-| "a
-| b"
=> "a
=> b"
(let ((print-escape-newlines t))
(prin1 "a\nb"))
-| "a\nb"
=> "a
=> b"
In the second expression, the local binding of
`print-escape-newlines' is in effect during the call to `prin1',
but not during the printing of the result.
- Variable: print-length
The value of this variable is the maximum number of elements of a
list that will be printed. If the list being printed has more
than this many elements, then it is abbreviated with an ellipsis.
If the value is `nil' (the default), then there is no limit.
(setq print-length 2)
=> 2
(print '(1 2 3 4 5))
-| (1 2 ...)
=> (1 2 ...)
- Variable: print-level
The value of this variable is the maximum depth of nesting of
parentheses that will be printed. Any list or vector at a depth
exceeding this limit is abbreviated with an ellipsis. A value of
`nil' (which is the default) means no limit.
This variable exists in version 19 and later versions.
File: elisp, Node: Minibuffers, Next: Command Loop, Prev: Streams, Up: Top
Minibuffers
***********
A "minibuffer" is a special buffer that Emacs commands use to read
arguments more complicated than the single numeric prefix argument.
These arguments include file names, buffer names, and command names (as
in `M-x'). The minibuffer is displayed on the bottom line of the
screen, in the same place as the echo area, but only while it is in use
for reading an argument.
* Menu:
* Intro to Minibuffers:: Basic information about minibuffers.
* Text from Minibuffer:: How to read a straight text string.
* Object from Minibuffer:: How to read a Lisp object or expression.
* Minibuffer History:: Recording previous minibuffer inputs
so the user can reuse them.
* Completion:: How to invoke and customize completion.
* Yes-or-No Queries:: Asking a question with a simple answer.
* Multiple Queries:: Asking a series of similar questions.
* Minibuffer Misc:: Various customization hooks and variables.
File: elisp, Node: Intro to Minibuffers, Next: Text from Minibuffer, Up: Minibuffers
Introduction to Minibuffers
===========================
In most ways, a minibuffer is a normal Emacs buffer. Most operations
*within* a buffer, such as editing commands, work normally in a
minibuffer. However, many operations for managing buffers do not apply
to minibuffers. The name of a minibuffer always has the form
` *Minibuf-NUMBER', and it cannot be changed. Minibuffers are
displayed only in special windows used only for minibuffers; these
windows always appear at the bottom of a frame. (Sometime frames have
no minibuffer window, and sometimes a special kind of frame contains
nothing but a minibuffer window; see *Note Minibuffers and Frames::.)
The minibuffers window is normally a single line; you can resize it
temporarily with the window sizing commands, but reverts to its normal
size when the minibuffer is exited.
A "recursive minibuffer" may be created when there is an active
minibuffer and a command is invoked that requires input from a
minibuffer. The first minibuffer is named ` *Minibuf-0*'. Recursive
minibuffers are named by incrementing the number at the end of the
name. (The names begin with a space so that they won't show up in
normal buffer lists.) Of several recursive minibuffers, the innermost
(or most recently entered) is the active minibuffer. We usually call
this "the" minibuffer. You can permit or forbid recursive minibuffers
by setting the variable `enable-recursive-minibuffers' or by putting
properties of that name on command symbols (*note Minibuffer Misc::.).
Like other buffers, a minibuffer may use any of several local keymaps
(*note Keymaps::.); these contain various exit commands and in some
cases completion commands. *Note Completion::.
* `minibuffer-local-map' is for ordinary input (no completion).
* `minibuffer-local-ns-map' is similar, except that SPC exits just
like RET. This is used mainly for Mocklisp compatibility.
* `minibuffer-local-completion-map' is for permissive completion.
* `minibuffer-local-must-match-map' is for strict completion and for
cautious completion.
File: elisp, Node: Text from Minibuffer, Next: Object from Minibuffer, Prev: Intro to Minibuffers, Up: Minibuffers
Reading Text Strings with the Minibuffer
========================================
The minibuffer is usually used to read text which is returned as a
string, but can also be used to read a Lisp object in textual form. The
most basic primitive for minibuffer input is `read-from-minibuffer'.
- Function: read-from-minibuffer PROMPT-STRING &optional INITIAL
KEYMAP READ HIST
This function is the most general way to get input through the
minibuffer. By default, it accepts arbitrary text and returns it
as a string; however, if READ is non-`nil', then it uses `read' to
convert the text into a Lisp object (*note Input Functions::.).
The first thing this function does is to activate a minibuffer and
display it with PROMPT-STRING as the prompt. This value must be a
string.
Then, if INITIAL is a string; its contents are inserted into the
minibuffer as initial contents. The text thus inserted is treated
as if the user had inserted it; the user can alter it with Emacs
editing commands.
The value of INITIAL may also be a cons cell of the form `(STRING
. POSITION)'. This means to insert STRING in the minibuffer but
put the cursor POSITION characters from the beginning, rather than
at the end.
If KEYMAP is non-`nil', that keymap is the local keymap to use
while reading. If KEYMAP is omitted or `nil', the value of
`minibuffer-local-map' is used as the keymap. Specifying a keymap
is the most important way to customize minibuffer input for
various applications including completion.
The argument HIST specifies which history list variable to use for
saving the input and for history commands used in the minibuffer.
It defaults to `minibuffer-history'. *Note Minibuffer History::.
When the user types a command to exit the minibuffer, the current
minibuffer contents are usually made into a string which becomes
the value of `read-from-minibuffer'. However, if READ is
non-`nil', `read-from-minibuffer' converts the result to a Lisp
object, and returns that object, unevaluated.
Suppose, for example, you are writing a search command and want to
record the last search string and provide it as a default for the
next search. Suppose that the previous search string is stored in
the variable `last-search-string'. Here is how you can read a
search string while providing the previous string as initial input
to be edited:
(read-from-minibuffer "Find string: " last-search-string)
Assuming the value of `last-search-string' is `No', and the user
wants to search for `Nope', the interaction looks like this:
(setq last-search-string "No")
(read-from-minibuffer "Find string: " last-search-string)
---------- Buffer: Minibuffer ----------
Find string: No-!-
---------- Buffer: Minibuffer ----------
;; The user now types `pe RET':
=> "Nope"
This technique is no longer preferred for most applications; it is
usually better to use a history list.
- Function: read-string PROMPT &optional INITIAL
This function reads a string from the minibuffer and returns it.
The arguments PROMPT and INITIAL are used as in
`read-from-minibuffer'.
This is a simplified interface to the `read-from-minibuffer'
function:
(read-string PROMPT INITIAL)
==
(read-from-minibuffer PROMPT INITIAL nil nil)
- Variable: minibuffer-local-map
This is the default local keymap for reading from the minibuffer.
It is the keymap used by the minibuffer for local bindings in the
function `read-string'. By default, it makes the following
bindings:
LFD
`exit-minibuffer'
RET
`exit-minibuffer'
`C-g'
`abort-recursive-edit'
`M-n' and `M-p'
`next-history-element' and `previous-history-element'
`M-r'
`next-matching-history-element'
`M-s'
`previous-matching-history-element'
- Function: read-no-blanks-input PROMPT &optional INITIAL
This function reads a string from the minibuffer, but does not
allow whitespace characters as part of the input: instead, those
characters terminate the input. The arguments PROMPT and INITIAL
are used as in `read-from-minibuffer'.
This is a simplified interface to the `read-from-minibuffer'
function, and passes the value of the `minibuffer-local-ns-map'
keymap as the KEYMAP argument for that function. Since the keymap
`minibuffer-local-ns-map' does not rebind `C-q', it *is* possible
to put a space into the string, by quoting it.
(read-no-blanks-input PROMPT INITIAL)
==
(read-from-minibuffer PROMPT INITIAL minibuffer-local-ns-map)
- Variable: minibuffer-local-ns-map
This built-in variable is the keymap used as the minibuffer local
keymap in the function `read-no-blanks-input'. By default, it
makes the following bindings:
LFD
`exit-minibuffer'
SPC
`exit-minibuffer'
TAB
`exit-minibuffer'
RET
`exit-minibuffer'
`C-g'
`abort-recursive-edit'
`?'
`self-insert-and-exit'
`M-n' and `M-p'
`next-history-element' and `previous-history-element'
`M-r'
`next-matching-history-element'
`M-s'
`previous-matching-history-element'
File: elisp, Node: Object from Minibuffer, Next: Minibuffer History, Prev: Text from Minibuffer, Up: Minibuffers
Reading Lisp Objects with the Minibuffer
========================================
This section describes functions for reading Lisp objects with the
minibuffer.
- Function: read-minibuffer PROMPT &optional INITIAL
This function reads a Lisp object in the minibuffer and returns it,
without evaluating it. The arguments PROMPT and INITIAL are used
as in `read-from-minibuffer'; in particular, INITIAL must be a
string or `nil'.
This is a simplified interface to the `read-from-minibuffer'
function:
(read-minibuffer PROMPT INITIAL)
==
(read-from-minibuffer PROMPT INITIAL nil t)
Here is an example in which we supply the string `"(testing)"' as
initial input:
(read-minibuffer
"Enter an expression: " (format "%s" '(testing)))
;; Here is how the minibuffer is displayed:
---------- Buffer: Minibuffer ----------
Enter an expression: (testing)-!-
---------- Buffer: Minibuffer ----------
The user can type RET immediately to use the initial input as a
default, or can edit the input.
- Function: eval-minibuffer PROMPT &optional INITIAL
This function reads a Lisp expression in the minibuffer, evaluates
it, then returns the result. The arguments PROMPT and INITIAL are
used as in `read-from-minibuffer'.
This function simply evaluates the result of a call to
`read-minibuffer':
(eval-minibuffer PROMPT INITIAL)
==
(eval (read-minibuffer PROMPT INITIAL))
- Function: edit-and-eval-command PROMPT FORM
This function reads a Lisp expression in the minibuffer, and then
evaluates it. The difference between this command and
`eval-minibuffer' is that here the initial FORM is not optional
and it is treated as a Lisp object to be converted to printed
representation rather than as a string of text. It is printed with
`prin1', so if it is a string, double-quote characters (`"')
appear in the initial text. *Note Output Functions::.
The first thing `edit-and-eval-command' does is to activate the
minibuffer with PROMPT as the prompt. Then it inserts the printed
representation of FORM in the minibuffer, and lets the user edit.
When the user exits the minibuffer, the edited text is read with
`read' and then evaluated. The resulting value becomes the value
of `edit-and-eval-command'.
In the following example, we offer the user an expression with
initial text which is a valid form already:
(edit-and-eval-command "Please edit: " '(forward-word 1))
;; After evaluating the preceding expression,
;; the following appears in the minibuffer:
---------- Buffer: Minibuffer ----------
Please edit: (forward-word 1)-!-
---------- Buffer: Minibuffer ----------
Typing RET right away would exit the minibuffer and evaluate the
expression, thus moving point forward one word.
`edit-and-eval-command' returns `nil' in this example.
File: elisp, Node: Minibuffer History, Next: Completion, Prev: Object from Minibuffer, Up: Minibuffers
Minibuffer History
==================
A minibuffer history list records previous minibuffer inputs so the
user can reuse them conveniently. There are many separate history lists
which contain different kinds of inputs. The Lisp programmer's job is
to specify the right history list for each use of the minibuffer.
The basic minibuffer input functions `read-from-minibuffer' and
`completing-read' both accept an optional argument named HIST which is
how you specify the history list. Here are the possible values:
VARIABLE
If you specify a variable (a symbol), that variable is the history
list.
(VARIABLE . STARTPOS)
If you specify a cons cell of this form, then VARIABLE is the
history list variable, and STARTPOS specifies the initial history
position (an integer, counting from zero which specifies the most
recent element of the history).
If you specify STARTPOS, then you should also specify that element
of the history as INITIAL, for consistency.
If you don't specify HIST, then the default history list
`minibuffer-history' is used. For other standard history lists, see
below. You can also create your own history list variable; just
initialize it to `nil' before the first use. The value of the history
list variable is a list of strings, most recent first.
Both `read-from-minibuffer' and `completing-read' add new elements
to the history list automatically, and provide commands to allow the
user to reuse items on the list. The only thing your program needs to
do to use a history list is to initialize it and to pass its name to
the input functions when you wish. But it is safe to modify the list
by hand when the minibuffer input functions are not using it.
- Variable: minibuffer-history
The default history list for minibuffer history input.
- Variable: query-replace-history
A history list for arguments to `query-replace' (and similar
arguments to other commands).
- Variable: file-name-history
A history list for file name arguments.
File: elisp, Node: Completion, Next: Yes-or-No Queries, Prev: Minibuffer History, Up: Minibuffers
Completion
==========
"Completion" is a feature that fills in the rest of a name starting
from an abbreviation for it. Completion works by comparing the user's
input against a list of valid names and determining how much of the
name is determined uniquely by what the user has typed.
For example, when you type `C-x b' (`switch-to-buffer') and then
type the first few letters of the name of the buffer to which you wish
to switch, and then type TAB (`minibuffer-complete'), Emacs extends the
name as far as it can. Standard Emacs commands offer completion for
names of symbols, files, buffers, and processes; with the functions in
this section, you can implement completion for other kinds of names.
The `try-completion' function is the basic primitive for completion:
it returns the longest determined completion of a given initial string,
with a given set of strings to match against.
The function `completing-read' provides a higher-level interface for
completion. A call to `completing-read' specifies how to determine the
list of valid names. The function then activates the minibuffer with a
local keymap that binds a few keys to commands useful for completion.
Other functions provide convenient simple interfaces for reading
certain kinds of names with completion.
* Menu:
* Basic Completion:: Low-level functions for completing strings.
(These are too low level to use the minibuffer.)
* Programmed Completion:: Finding the completions for a given file name.
* Minibuffer Completion:: Invoking the minibuffer with completion.
* Completion Commands:: Minibuffer commands that do completion.
* High-Level Completion:: Convenient special cases of completion
(reading buffer name, file name, etc.)
* Reading File Names:: Using completion to read file names.
* Lisp Symbol Completion:: Completing the name of a symbol.
File: elisp, Node: Basic Completion, Next: Programmed Completion, Up: Completion
Basic Completion Functions
--------------------------
- Function: try-completion STRING COLLECTION &optional PREDICATE
This function returns the longest common substring of all possible
completions of STRING in COLLECTION. The value of COLLECTION must
be an alist, an obarray, or a function which implements a virtual
set of strings.
If COLLECTION is an alist (*note Association Lists::.), completion
compares the CAR of each cons cell in it against STRING; if the
beginning of the CAR equals STRING, the cons cell matches. If no
cons cells match, `try-completion' returns `nil'. If only one
cons cell matches, and the match is exact, then `try-completion'
returns `t'. Otherwise, the value is the longest initial sequence
common to all the matching strings in the alist.
If COLLECTION is an obarray (*note Creating Symbols::.), the names
of all symbols in the obarray form the space of possible
completions. They are tested and used just like the CARs of the
elements of an association list. (The global variable `obarray'
holds an obarray containing the names of all interned Lisp
symbols.)
Note that the only valid way to make a new obarray is to create it
empty and then add symbols to it one by one using `intern'. Also,
you cannot intern a given symbol in more than one obarray.
If the argument PREDICATE is non-`nil', then it must be a function
of one argument. It is used to test each possible match, and the
match is accepted only if PREDICATE returns non-`nil'. The
argument given to PREDICATE is either a cons cell from the alist
(the CAR of which is a string) or else it is a symbol (*not* a
symbol name) from the obarray.
It is also possible to use a function symbol as COLLECTION. Then
the function is solely responsible for performing completion;
`try-completion' returns whatever this function returns. The
function is called with three arguments: STRING, PREDICATE and
`nil'. (The reason for the third argument is so that the same
function can be used in `all-completions' and do the appropriate
thing in either case.) *Note Programmed Completion::.
In the first of the following examples, the string `foo' is
matched by three of the alist CARs. All of the matches begin with
the characters `fooba', so that is the result. In the second
example, there is only one possible match, and it is exact, so the
value is `t'.
(try-completion
"foo"
'(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4)))
=> "fooba"
(try-completion "foo" '(("barfoo" 2) ("foo" 3)))
=> t
In the following example, numerous symbols begin with the
characters `forw', and all of them begin with the word `forward'.
In most of the symbols, this is followed with a `-', but not in
all, so no more than `forward' can be completed.
(try-completion "forw" obarray)
=> "forward"
Finally, in the following example, only two of the three possible
matches pass the predicate `test' (the string `foobaz' is too
short). Both of those begin with the string `foobar'.
(defun test (s)
(> (length (car s)) 6))
=> test
(try-completion
"foo"
'(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
'test)
=> "foobar"
- Function: all-completions STRING COLLECTION &optional PREDICATE
This function returns a list of all possible completions, instead
of the longest substring they share. The parameters to this
function are the same as to `try-completion'.
If COLLECTION is a function, it is called with three arguments:
STRING, PREDICATE and `t', and `all-completions' returns whatever
the function returns. *Note Programmed Completion::.
Here is an example, using the function `test' shown in the example
for `try-completion':
(defun test (s)
(> (length (car s)) 6))
=> test
(all-completions
"foo"
'(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
(function test))
=> ("foobar1" "foobar2")
- Variable: completion-ignore-case
If the value of this variable is non-`nil', Emacs does not
consider case significant in completion.
The two functions `try-completion' and `all-completions' have
nothing in themselves to do with minibuffers. However, completion is
most often used there, which is why it is described in this chapter.
File: elisp, Node: Programmed Completion, Next: Minibuffer Completion, Prev: Basic Completion, Up: Completion
Programmed Completion
---------------------
Sometimes it is not possible to create an alist or an obarray
containing all the intended possible completions. In such a case, you
can supply your own function to compute the completion of a given
string. This is called "programmed completion".
To use this feature, pass a symbol with a function definition as the
COLLECTION argument to `completing-read'. This command arranges to
pass the function along to `try-completion' and `all-completions',
which will then let your function do all the work.
The completion function should accept three arguments:
* The string to be completed.
* The predicate function to filter possible matches, or `nil' if
none. Your function should call the predicate for each possible
match and ignore the possible match if the predicate returns `nil'.
* A flag specifying the type of operation.
There are three flag values for three operations:
* `nil' specifies `try-completion'. The completion function should
return the completion of the specified string, or `t' if the
string is an exact match already, or `nil' if the string matches no
possibility.
* `t' specifies `all-completions'. The completion function should
return a list of all possible completions of the specified string.
* `lambda' specifies a test for an exact match. The completion
function should return `t' if the specified string is an exact
match for some possibility; `nil' otherwise.
It would be consistent and clean for completion functions to allow
lambda expressions (lists which are functions) as well as function
symbols as COLLECTION, but this is impossible. Lists as completion
tables are already assigned another meaning--as alists. It would be
unreliable to fail to handle an alist normally because it is also a
possible function. So you must arrange for any function you wish to
use for completion to be encapsulated in a symbol.
Emacs uses programmed completion when completing file names. *Note
File Name Completion::.
File: elisp, Node: Minibuffer Completion, Next: Completion Commands, Prev: Programmed Completion, Up: Completion
Completion and the Minibuffer
-----------------------------
This section describes the basic interface for reading from the
minibuffer with completion.
- Function: completing-read PROMPT COLLECTION &optional PREDICATE
REQUIRE-MATCH INITIAL HIST
This function reads a string in the minibuffer, assisting the user
by providing completion. It activates the minibuffer with prompt
PROMPT, which must be a string. If INITIAL is non-`nil',
`completing-read' inserts it into the minibuffer as part of the
input. Then it allows the user to edit the input, providing
several commands to attempt completion.
The actual completion is done by passing COLLECTION and PREDICATE
to the function `try-completion'. This happens in certain
commands bound in the local keymaps used for completion.
If REQUIRE-MATCH is `t', the user is not allowed to exit unless
the input completes to an element of COLLECTION. If REQUIRE-MATCH
is neither `nil' nor `t', then `completing-read' does not exit
unless the input typed is itself an element of COLLECTION. To
accomplish this, `completing-read' calls `read-minibuffer'. It
uses the value of `minibuffer-local-completion-map' as the keymap
if REQUIRE-MATCH is `nil', and uses
`minibuffer-local-must-match-map' if REQUIRE-MATCH is non-`nil'.
The argument HIST specifies which history list variable to use for
saving the input and for minibuffer history commands. It defaults
to `minibuffer-history'. *Note Minibuffer History::.
Case is ignored when comparing the input against the possible
matches if the built-in variable `completion-ignore-case' is
non-`nil'. *Note Basic Completion::.
For example:
(completing-read
"Complete a foo: "
'(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
nil t "fo")
;; After evaluating the preceding expression,
;; the following appears in the minibuffer:
---------- Buffer: Minibuffer ----------
Complete a foo: fo-!-
---------- Buffer: Minibuffer ----------
If the user then types `DEL DEL b RET', `completing-read' returns
`barfoo'.
The `completing-read' function binds three variables to pass
information to the commands which actually do completion. Here
they are:
`minibuffer-completion-table'
This variable is bound to the COLLECTION argument. It is
passed to the `try-completion' function.
`minibuffer-completion-predicate'
This variable is bound to the PREDICATE argument. It is
passed to the `try-completion' function.
`minibuffer-completion-confirm'
This variable is bound to the REQUIRE-MATCH argument. It is
used in the `minibuffer-complete-and-exit' function.
File: elisp, Node: Completion Commands, Next: High-Level Completion, Prev: Minibuffer Completion, Up: Completion
Minibuffer Commands That Do Completion
--------------------------------------
This section describes the keymaps, commands and user options used in
the minibuffer to do completion.
- Variable: minibuffer-local-completion-map
`completing-read' uses this value as the local keymap when an
exact match of one of the completions is not required. By
default, this keymap makes the following bindings:
`?'
`minibuffer-completion-help'
SPC
`minibuffer-complete-word'
TAB
`minibuffer-complete'
with other characters bound as in `minibuffer-local-map'.
- Variable: minibuffer-local-must-match-map
`completing-read' uses this value as the local keymap when an
exact match of one of the completions is required. Therefore, no
keys are bound to `exit-minibuffer', the command which exits the
minibuffer unconditionally. By default, this keymap makes the
following bindings:
`?'
`minibuffer-completion-help'
SPC
`minibuffer-complete-word'
TAB
`minibuffer-complete'
LFD
`minibuffer-complete-and-exit'
RET
`minibuffer-complete-and-exit'
with other characters bound as in `minibuffer-local-map'.
- Variable: minibuffer-completion-table
The value of this variable is the alist or obarray used for
completion in the minibuffer. This is the global variable that
contains what `completing-read' passes to `try-completion'. It is
used by all the minibuffer completion functions, such as
`minibuffer-complete-word'.
- Variable: minibuffer-completion-predicate
This variable's value is the predicate that `completing-read'
passes to `try-completion'. The variable is also used by the other
minibuffer completion functions.
- Command: minibuffer-complete-word
This function completes the minibuffer contents by at most a single
word. Even if the minibuffer contents have only one completion,
`minibuffer-complete-word' does not add any characters beyond the
first character that is not a word constituent. *Note Syntax
Tables::.
- Command: minibuffer-complete
This function completes the minibuffer contents as far as possible.
- Command: minibuffer-complete-and-exit
This function completes the minibuffer contents, and exits if
confirmation is not required, i.e., if
`minibuffer-completion-confirm' is non-`nil'. If confirmation
*is* required, it is given by repeating this command immediately.
- Variable: minibuffer-completion-confirm
When the value of this variable is non-`nil', Emacs asks for
confirmation of a completion before exiting the minibuffer. The
function `minibuffer-complete-and-exit' checks the value of this
variable before it exits.
- Command: minibuffer-completion-help
This function creates a list of the possible completions of the
current minibuffer contents. It works by calling `all-completions'
using the value of the variable `minibuffer-completion-table' as
the COLLECTION argument, and the value of
`minibuffer-completion-predicate' as the PREDICATE argument. The
list of completions is displayed as text in a buffer named
`*Completions*'.
- Function: display-completion-list COMPLETIONS
This function displays COMPLETIONS to the stream in
`standard-output', usually a buffer. (*Note Streams::, for more
information about streams.) The argument COMPLETIONS is normally
a list of completions just returned by `all-completions', but it
does not have to be. Each element may be a symbol or a string,
either of which is simply printed, or a list of two strings, which
is printed as if the strings were concatenated.
This function is called by `minibuffer-completion-help'. The most
common way to use it is together with
`with-output-to-temp-buffer', like this:
(with-output-to-temp-buffer " *Completions*"
(display-completion-list
(all-completions (buffer-string) my-alist)))
- User Option: completion-auto-help
If this variable is non-`nil', the completion commands
automatically display a list of possible completions whenever
nothing can be completed because the next character is not
uniquely determined.
File: elisp, Node: High-Level Completion, Next: Reading File Names, Prev: Completion Commands, Up: Completion
High-Level Completion Functions
--------------------------------
This section describes the higher-level convenient functions for
reading certain sorts of names with completion.
- Function: read-buffer PROMPT &optional DEFAULT EXISTING
This function reads the name of a buffer and returns it as a
string. The argument DEFAULT is the default name to use, the
value to return if the user exits with an empty minibuffer. If
non-`nil', it should be a string. It is mentioned in the prompt,
but is not inserted in the minibuffer as initial input.
If EXISTING is non-`nil', then the name specified must be that of
an existing buffer. The usual commands to exit the minibuffer do
not exit if the text is not valid, and RET does completion to
attempt to find a valid name. (However, DEFAULT is not checked
for this; it is returned, whatever it is, if the user exits with
the minibuffer empty.)
In the following example, the user enters `minibuffer.t', and then
types RET. The argument EXISTING is `t', and the only buffer name
starting with the given input is `minibuffer.texi', so that name
is the value.
(read-buffer "Buffer name? " "foo" t)
;; After evaluating the preceding expression,
;; the following prompt appears,
;; with an empty minibuffer:
---------- Buffer: Minibuffer ----------
Buffer name? (default foo) -!-
---------- Buffer: Minibuffer ----------
;; The user types `minibuffer.t RET'.
=> "minibuffer.texi"
- Function: read-command PROMPT
This function reads the name of a command and returns it as a Lisp
symbol. The argument PROMPT is used as in `read-from-minibuffer'.
Recall that a command is anything for which `commandp' returns
`t', and a command name is a symbol for which `commandp' returns
`t'. *Note Interactive Call::.
(read-command "Command name? ")
;; After evaluating the preceding expression,
;; the following appears in the minibuffer:
---------- Buffer: Minibuffer ----------
Command name?
---------- Buffer: Minibuffer ----------
If the user types `forward-c RET', then this function returns
`forward-char'.
The `read-command' function is a simplified interface to the
`completing-read' function. It uses the `commandp' predicate to
allow only commands to be entered, and it uses the variable
`obarray' so as to be able to complete all extant Lisp symbols:
(read-command PROMPT)
==
(intern (completing-read PROMPT obarray 'commandp t nil))
- Function: read-variable PROMPT
This function reads the name of a user variable and returns it as a
symbol.
(read-variable "Variable name? ")
;; After evaluating the preceding expression,
;; the following prompt appears,
;; with an empty minibuffer:
---------- Buffer: Minibuffer ----------
Variable name? -!-
---------- Buffer: Minibuffer ----------
If the user then types `fill-p RET', `read-variable' will return
`fill-prefix'.
This function is similar to `read-command', but uses the predicate
`user-variable-p' instead of `commandp':
(read-variable PROMPT)
==
(intern
(completing-read PROMPT obarray 'user-variable-p t nil))
File: elisp, Node: Reading File Names, Next: Lisp Symbol Completion, Prev: High-Level Completion, Up: Completion
Reading File Names
------------------
Here is another high-level completion function, designed for reading
a file name. It provides special features including automatic insertion
of the default directory.
- Function: read-file-name PROMPT &optional DIRECTORY DEFAULT EXISTING
INITIAL
This function reads a file name in the minibuffer, prompting with
PROMPT and providing completion. If DEFAULT is non-`nil', then
the function returns DEFAULT if the user just types RET.
If EXISTING is non-`nil', then the name must refer to an existing
file; then RET performs completion to make the name valid if
possible, and then refuses to exit if it is not valid. If the
value of EXISTING is neither `nil' nor `t', then RET also requires
confirmation after completion.
The argument DIRECTORY specifies the directory to use for
completion of relative file names. Usually it is inserted in the
minibuffer as initial input as well. It defaults to the current
buffer's default directory.
If you specify INITIAL, that is an initial file name to insert in
the buffer along with DIRECTORY. In this case, point goes after
DIRECTORY, before INITIAL. The default for INITIAL is
`nil'--don't insert any file name. To see what INITIAL does, try
the command `C-x C-v'.
Here is an example:
(read-file-name "The file is ")
;; After evaluating the preceding expression,
;; the following appears in the minibuffer:
---------- Buffer: Minibuffer ----------
The file is /gp/gnu/elisp/-!-
---------- Buffer: Minibuffer ----------
Typing `manual TAB' results in the following:
---------- Buffer: Minibuffer ----------
The file is /gp/gnu/elisp/manual.texi-!-
---------- Buffer: Minibuffer ----------
If the user types RET, `read-file-name' returns
`"/gp/gnu/elisp/manual.texi"'.
- User Option: insert-default-directory
This variable is used by `read-file-name'. Its value controls
whether `read-file-name' starts by placing the name of the default
directory in the minibuffer, plus the initial file name if any.
If the value of this variable is `nil', then `read-file-name' does
not place any initial input in the minibuffer. In that case, the
default directory is still used for completion of relative file
names, but is not displayed.
For example:
;; Here the minibuffer starts out containing the default directory.
(let ((insert-default-directory t))
(read-file-name "The file is "))
---------- Buffer: Minibuffer ----------
The file is ~lewis/manual/-!-
---------- Buffer: Minibuffer ----------
;; Here the minibuffer is empty and only the prompt
;; appears on its line.
(let ((insert-default-directory nil))
(read-file-name "The file is "))
---------- Buffer: Minibuffer ----------
The file is -!-
---------- Buffer: Minibuffer ----------
File: elisp, Node: Lisp Symbol Completion, Prev: Reading File Names, Up: Completion
Lisp Symbol Completion
----------------------
If you type a part of a symbol, and then type `M-TAB'
(`lisp-complete-symbol'), this command attempts to fill in as much more
of the symbol name as it can. Not only does this save typing, but it
can help you with the name of a symbol that you have partially
forgotten.
- Command: lisp-complete-symbol
This function performs completion on the symbol name preceding
point. The name is completed against the symbols in the global
variable `obarray', and characters from the completion are
inserted into the buffer, making the name longer. If there is
more than one completion, a list of all possible completions is
placed in the `*Help*' buffer. The bell rings if there is no
possible completion in `obarray'.
If an open parenthesis immediately precedes the name, only symbols
with function definitions are considered. (By reducing the number
of alternatives, this may succeed in completing more characters.)
Otherwise, symbols with either a function definition, a value, or
at least one property are considered.
`lisp-complete-symbol' returns `t' if the symbol had an exact, and
unique, match; otherwise, it returns `nil'.
In the following example, the user has already inserted `(forwa'
into the buffer `foo.el'. The command `lisp-complete-symbol' then
completes the name to `(forward-'.
---------- Buffer: foo.el ----------
(forwa-!-
---------- Buffer: foo.el ----------
(lisp-complete-symbol)
=> nil
---------- Buffer: foo.el ----------
(forward--!-
---------- Buffer: foo.el ----------